/*
 *   This program is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

/*
 *    Loader.java
 *    Copyright (C) 2000-2012 University of Waikato, Hamilton, New Zealand
 *
 */

package weka.core.converters;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.Serializable;

import weka.core.Instance;
import weka.core.Instances;

/**
 * Interface to something that can load Instances from an input source in some
 * format.
 * 
 * @author Mark Hall (mhall@cs.waikato.ac.nz)
 * @version $Revision$
 */
public interface Loader extends Serializable {

    /**
     * Exception that implementers can throw from getStructure() when they have not
     * been configured sufficiently in order to read the structure (or data).
     * 
     * @author Mark Hall (mhall{[at]}pentaho{[dot]}com)
     */
    public static class StructureNotReadyException extends IOException {

        /**
         * For Serialization
         */
        private static final long serialVersionUID = 1938493033987645828L;

        public StructureNotReadyException(String message) {
            super(message);
        }
    }

    /** The retrieval modes */
    public static final int NONE = 0;
    public static final int BATCH = 1;
    public static final int INCREMENTAL = 2;

    /**
     * Sets the retrieval mode. Note: Some loaders may not be able to implement
     * incremental loading.
     * 
     * @param mode the retrieval mode
     */
    void setRetrieval(int mode);

    /**
     * Resets the Loader object ready to begin loading. If there is an existing
     * source, implementations should attempt to reset in such a fashion as to be
     * able to load from the beginning of the source.
     * 
     * @throws Exception if Loader can't be reset for some reason.
     */
    void reset() throws Exception;

    /*
     * @ public model instance boolean model_structureDetermined
     * 
     * @ initially: model_structureDetermined == false;
     * 
     * @
     */

    /*
     * @ public model instance boolean model_sourceSupplied
     * 
     * @ initially: model_sourceSupplied == false;
     * 
     * @
     */

    /**
     * Resets the Loader object and sets the source of the data set to be the
     * supplied File object.
     * 
     * @param file the File
     * @throws IOException if an error occurs support loading from a File.
     * 
     *                     <pre>
     * <jml>
     *    public_normal_behavior
     *      requires: file != null
     *                && (* file exists *);
     *      modifiable: model_sourceSupplied, model_structureDetermined;
     *      ensures: model_sourceSupplied == true 
     *               && model_structureDetermined == false;
     *  also
     *    public_exceptional_behavior
     *      requires: file == null
     *                || (* file does not exist *);
     *    signals: (IOException);
     * </jml>
     *                     </pre>
     */
    void setSource(File file) throws IOException;

    /**
     * Resets the Loader object and sets the source of the data set to be the
     * supplied InputStream.
     * 
     * @param input the source InputStream
     * @throws IOException if this Loader doesn't support loading from a File.
     */
    void setSource(InputStream input) throws IOException;

    /**
     * Determines and returns (if possible) the structure (internally the header) of
     * the data set as an empty set of instances.
     * 
     * @return the structure of the data set as an empty set of Instances
     * @throws IOException if there is no source or parsing fails
     * 
     *                     <pre>
     * <jml>
     *    public_normal_behavior
     *      requires: model_sourceSupplied == true
     *                && model_structureDetermined == false
     *                && (* successful parse *);
     *      modifiable: model_structureDetermined;
     *      ensures: \result != null
     *               && \result.numInstances() == 0
     *               && model_structureDetermined == true;
     *  also
     *    public_exceptional_behavior
     *      requires: model_sourceSupplied == false
     *                || (* unsuccessful parse *);
     *      signals: (IOException);
     * </jml>
     *                     </pre>
     */
    Instances getStructure() throws IOException;

    /**
     * Return the full data set. If the structure hasn't yet been determined by a
     * call to getStructure then the method should do so before processing the rest
     * of the data set.
     * 
     * @return the full data set as an Instances object
     * @throws IOException if there is an error during parsing or if getNextInstance
     *                     has been called on this source (either incremental or
     *                     batch loading can be used, not both).
     * 
     *                     <pre>
     * <jml>
     *    public_normal_behavior
     *      requires: model_sourceSupplied == true
     *                && (* successful parse *);
     *      modifiable: model_structureDetermined;
     *      ensures: \result != null
     *               && \result.numInstances() >= 0
     *               && model_structureDetermined == true;
     *  also
     *    public_exceptional_behavior
     *      requires: model_sourceSupplied == false
     *                || (* unsuccessful parse *);
     *      signals: (IOException);
     * </jml>
     *                     </pre>
     */
    Instances getDataSet() throws IOException;

    /**
     * Read the data set incrementally---get the next instance in the data set or
     * returns null if there are no more instances to get. If the structure hasn't
     * yet been determined by a call to getStructure then method should do so before
     * returning the next instance in the data set.
     * 
     * If it is not possible to read the data set incrementally (ie. in cases where
     * the data set structure cannot be fully established before all instances have
     * been seen) then an exception should be thrown.
     * 
     * @param structure the dataset header information, will get updated in case of
     *                  string or relational attributes
     * @return the next instance in the data set as an Instance object or null if
     *         there are no more instances to be read
     * @throws IOException if there is an error during parsing or if getDataSet has
     *                     been called on this source (either incremental or batch
     *                     loading can be used, not both).
     */
    Instance getNextInstance(Instances structure) throws IOException;
}
